Context

The torchfx audit (docs/history/library-review-torchfx-2026-05-13.md, PR #39) ruled out adopting matteospanio/torchfx as a dependency — GPL v3 vs ASA's MIT is a one-way door — but flagged the underlying pattern as worth borrowing: a small filter primitive that batches per-band work and gives a clean hook for future GPU acceleration. This PR implements the minimum slice of that pattern that earns its complexity today: PR 1 of the audit's plan.

What changed

Three scipy-Butterworth bandpass call sites in analyze_detection.py (_bandpass_signal, the reverb per-band RT60 loop) were each re-implementing the same butter(4, [lo, hi], output='sos') + sosfiltfilt sequence with slightly different glue. They now share one BatchedBandpass instance per sample rate (cached via functools.lru_cache(maxsize=4)) that memoises SOS coefficients per (lo_hz, hi_hz).

The 7-band transient-density loop in analyze_per_band_transient_density and the Essentia BandPass call sites are intentionally out of scope for this PR. The transient-density swap is a candidate for a follow-on PR if and only if this one lands cleanly.

Files

Bit-identicality

Output is bit-identical to the previous inline implementation. The load-bearing test test_filter_one_matches_inline_scipy_bit_for_bit compares the new class against a literal copy of the pre-refactor _bandpass_signal arithmetic on a fixed-seed signal and asserts np.allclose(atol=1e-12, rtol=1e-12). The full pre/post snapshot of analyze.py output on a synthetic click-train fixture is zero-diff — including reverbDetail.perBandRt60. Phase 1 numbers do not move.

No JSON field changes, no schema changes, no new dependencies.

Forward-looking seam

BatchedBandpass(backend=...) is reserved for a future torch path — only "scipy" is implemented today; passing anything else raises ValueError. A future torch backend would land here if profiling shows per-band scipy filtering is hot. Until then, this is the simplest shape that earns its keep on consolidation alone.

Tests

$ ./venv/bin/python -m unittest tests.test_dsp_utils.BatchedBandpassTests -v
test_filter_many_accepts_reverb_bands_tuple_shape ... ok
test_filter_many_accepts_spectral_balance_dict_shape ... ok
test_filter_many_returns_same_arrays_as_per_band_loop ... ok
test_filter_one_matches_inline_scipy_bit_for_bit ... ok
test_filter_one_returns_none_for_empty_input ... ok
test_invalid_band_returns_none_or_absent_key ... ok
test_sos_coefficients_are_cached_per_band ... ok
test_unsupported_backend_raises ... ok
Ran 8 tests in 0.145s — OK

$ ./venv/bin/python -m unittest tests.test_analyze.ReverbDetailTests
Ran 7 tests in 1.796s — OK

$ ./venv/bin/python -m unittest discover -s tests
Ran 551 tests in 138.571s — OK

End-to-end pre/post snapshot of analyze.py on /tmp/reverb_test.wav (synthetic click train + 80 Hz drone): diff produces zero output.

Why this is worth it

This is a maintenance change per PURPOSE.md decision framework category #4 — it doesn't move Phase 1 numbers, doesn't change Phase 2 recommendations, isn't on the critical latency path. What it does buy: one place to add a torch-backed backend="torch" variant if profiling ever shows per-band scipy filtering is a hotspot, plus the audit conclusion ("don't add the dep, borrow the pattern") now has a concrete shape in the tree.

https://claude.ai/code/session_01WJ4q6kzeEMscgnSa9gRqQk

Generated by Claude Code